Contents | Previous | Next |
This chapter serves as the reference section for the JNI functions. It provides a complete listing of all the JNI functions. It also presents the exact layout of the JNI function table.
Note the use of the term "must" to describe restrictions on JNI programmers. For example, when you see that a certain JNI function must receive a non-NULL object, it is your responsibility to ensure that NULL is not passed to that JNI function. As a result, a JNI implementation does not need to perform NULL pointer checks in that JNI function.
A portion of this chapter is adapted from Netscape's JRI documentation.
The reference material groups functions by their usage. The reference section is organized by the following functional areas:
Each function is accessible at a fixed offset through the JNIEnv argument. The JNIEnv type is a pointer to a structure storing all JNI function pointers. It is defined as follows:
typedef const struct JNINativeInterface *JNIEnv;
The VM initializes the function table, as shown by Code Example 4-1. Note that the
first three entries are reserved for future compatibility with COM.
In addition, we reserve a number of additional NULL
entries near the beginning of the function table, so that, for
example, a future class-related JNI operation can be added after
FindClass, rather than at the end of the table.
Note that the function table can be shared among all JNI interface pointers.
const struct JNINativeInterface ... = { NULL, NULL, NULL, NULL, GetVersion, DefineClass, FindClass, FromReflectedMethod, FromReflectedField, ToReflectedMethod, GetSuperclass, IsAssignableFrom, ToReflectedField, Throw, ThrowNew, ExceptionOccurred, ExceptionDescribe, ExceptionClear, FatalError, PushLocalFrame, PopLocalFrame, NewGlobalRef, DeleteGlobalRef, DeleteLocalRef, IsSameObject, NewLocalRef, EnsureLocalCapacity, AllocObject, NewObject, NewObjectV, NewObjectA, GetObjectClass, IsInstanceOf, GetMethodID, CallObjectMethod, CallObjectMethodV, CallObjectMethodA, CallBooleanMethod, CallBooleanMethodV, CallBooleanMethodA, CallByteMethod, CallByteMethodV, CallByteMethodA, CallCharMethod, CallCharMethodV, CallCharMethodA, CallShortMethod, CallShortMethodV, CallShortMethodA, CallIntMethod, CallIntMethodV, CallIntMethodA, CallLongMethod, CallLongMethodV, CallLongMethodA, CallFloatMethod, CallFloatMethodV, CallFloatMethodA, CallDoubleMethod, CallDoubleMethodV, CallDoubleMethodA, CallVoidMethod, CallVoidMethodV, CallVoidMethodA, CallNonvirtualObjectMethod, CallNonvirtualObjectMethodV, CallNonvirtualObjectMethodA, CallNonvirtualBooleanMethod, CallNonvirtualBooleanMethodV, CallNonvirtualBooleanMethodA, CallNonvirtualByteMethod, CallNonvirtualByteMethodV, CallNonvirtualByteMethodA, CallNonvirtualCharMethod, CallNonvirtualCharMethodV, CallNonvirtualCharMethodA, CallNonvirtualShortMethod, CallNonvirtualShortMethodV, CallNonvirtualShortMethodA, CallNonvirtualIntMethod, CallNonvirtualIntMethodV, CallNonvirtualIntMethodA, CallNonvirtualLongMethod, CallNonvirtualLongMethodV, CallNonvirtualLongMethodA, CallNonvirtualFloatMethod, CallNonvirtualFloatMethodV, CallNonvirtualFloatMethodA, CallNonvirtualDoubleMethod, CallNonvirtualDoubleMethodV, CallNonvirtualDoubleMethodA, CallNonvirtualVoidMethod, CallNonvirtualVoidMethodV, CallNonvirtualVoidMethodA, GetFieldID, GetObjectField, GetBooleanField, GetByteField, GetCharField, GetShortField, GetIntField, GetLongField, GetFloatField, GetDoubleField, SetObjectField, SetBooleanField, SetByteField, SetCharField, SetShortField, SetIntField, SetLongField, SetFloatField, SetDoubleField, GetStaticMethodID, CallStaticObjectMethod, CallStaticObjectMethodV, CallStaticObjectMethodA, CallStaticBooleanMethod, CallStaticBooleanMethodV, CallStaticBooleanMethodA, CallStaticByteMethod, CallStaticByteMethodV, CallStaticByteMethodA, CallStaticCharMethod, CallStaticCharMethodV, CallStaticCharMethodA, CallStaticShortMethod, CallStaticShortMethodV, CallStaticShortMethodA, CallStaticIntMethod, CallStaticIntMethodV, CallStaticIntMethodA, CallStaticLongMethod, CallStaticLongMethodV, CallStaticLongMethodA, CallStaticFloatMethod, CallStaticFloatMethodV, CallStaticFloatMethodA, CallStaticDoubleMethod, CallStaticDoubleMethodV, CallStaticDoubleMethodA, CallStaticVoidMethod, CallStaticVoidMethodV, CallStaticVoidMethodA, GetStaticFieldID, GetStaticObjectField, GetStaticBooleanField, GetStaticByteField, GetStaticCharField, GetStaticShortField, GetStaticIntField, GetStaticLongField, GetStaticFloatField, GetStaticDoubleField, SetStaticObjectField, SetStaticBooleanField, SetStaticByteField, SetStaticCharField, SetStaticShortField, SetStaticIntField, SetStaticLongField, SetStaticFloatField, SetStaticDoubleField, NewString, GetStringLength, GetStringChars, ReleaseStringChars, NewStringUTF, GetStringUTFLength, GetStringUTFChars, ReleaseStringUTFChars, GetArrayLength, NewObjectArray, GetObjectArrayElement, SetObjectArrayElement, NewBooleanArray, NewByteArray, NewCharArray, NewShortArray, NewIntArray, NewLongArray, NewFloatArray, NewDoubleArray, GetBooleanArrayElements, GetByteArrayElements, GetCharArrayElements, GetShortArrayElements, GetIntArrayElements, GetLongArrayElements, GetFloatArrayElements, GetDoubleArrayElements, ReleaseBooleanArrayElements, ReleaseByteArrayElements, ReleaseCharArrayElements, ReleaseShortArrayElements, ReleaseIntArrayElements, ReleaseLongArrayElements, ReleaseFloatArrayElements, ReleaseDoubleArrayElements, GetBooleanArrayRegion, GetByteArrayRegion, GetCharArrayRegion, GetShortArrayRegion, GetIntArrayRegion, GetLongArrayRegion, GetFloatArrayRegion, GetDoubleArrayRegion, SetBooleanArrayRegion, SetByteArrayRegion, SetCharArrayRegion, SetShortArrayRegion, SetIntArrayRegion, SetLongArrayRegion, SetFloatArrayRegion, SetDoubleArrayRegion, RegisterNatives, UnregisterNatives, MonitorEnter, MonitorExit, GetJavaVM, GetStringRegion, GetStringUTFRegion, GetPrimitiveArrayCritical, ReleasePrimitiveArrayCritical, GetStringCritical, ReleaseStringCritical, NewWeakGlobalRef, DeleteWeakGlobalRef, ExceptionCheck, NewDirectByteBuffer, GetDirectBufferAddress, GetDirectBufferCapacity GetObjectRefType };
jint GetVersion(JNIEnv *env);
Returns the version of the native method interface.
Index 4 in the JNIEnv interface function table.
env
: the JNI interface pointer.
Returns the major version number in the higher 16 bits and the minor version number in the lower 16 bits.
In SDK/JRE 1.1, GetVersion()
returns
0x00010001
.
In SDK/JRE 1.2, GetVersion()
returns
0x00010002
.
In SDK/JRE 1.4, GetVersion()
returns
0x00010004
.
In SDK/JRE 1.6, GetVersion()
returns
0x00010006
.
#define JNI_VERSION_1_1 0x00010001 #define JNI_VERSION_1_2 0x00010002 /* Error codes */ #define JNI_EDETACHED (-2) /* thread detached from the VM */ #define JNI_EVERSION (-3) /* JNI version error
#define JNI_VERSION_1_4 0x00010004
#define JNI_VERSION_1_6 0x00010006
jclass DefineClass(JNIEnv *env, jobject loader,
const jbyte *buf, jsize bufLen);
Loads a class from a buffer of raw class data. The buffer containing the raw class data is not referenced by the VM after the DefineClass call returns, and it may be discarded if desired.
Index 5 in the JNIEnv interface function table.
env
: the JNI interface pointer.
loader
: a class loader assigned to the defined
class.
buf
: buffer containing the .class
file
data.
bufLen
: buffer length.
Returns a Java class object or NULL
if an error
occurs.
ClassFormatError
: if the class data does not
specify a valid class.
ClassCircularityError
: if a class or interface
would be its own superclass or superinterface.
OutOfMemoryError
: if the system runs out of
memory.
jclass FindClass(JNIEnv *env, const char
*name);
This function loads a locally-defined class. It searches the
directories and zip files specified by the CLASSPATH
environment variable for the class with the specified name.
Index 6 in the JNIEnv interface function table.
env
: the JNI interface pointer.
name
: a fully-qualified class name (that is, a
package name, delimited by "/
", followed by the class
name). If the name begins with "[
" (the array
signature character), it returns an array class.
Returns a class object from a fully-qualified name, or
NULL
if the class cannot be found.
ClassFormatError
: if the class data does not
specify a valid class.
ClassCircularityError
: if a class or interface
would be its own superclass or superinterface.
NoClassDefFoundError
: if no definition for a
requested class or interface can be found.
OutOfMemoryError
: if the system runs out of
memory.
In JDK 1.1, FindClass
searched only local classes
in CLASSPATH
. The resulting classes did not have a
class loader.
The Java security model has been extended to allow non-system
classes to load and call native methods. In the Java 2 Platform,
FindClass
locates the class loader associated with the
current native method. If the native code belongs to a system
class, no class loader will be involved. Otherwise, the proper
class loader will be invoked to load and link the named class.
When FindClass
is called through the Invocation
Interface, there is no current native method or its associated
class loader. In that case, the result of
ClassLoader.getBaseClassLoader
is used. This is the
class loader the virtual machine creates for applications, and is
able to locate classes listed in the java.class.path
property.
jclass GetSuperclass(JNIEnv *env, jclass
clazz);
If clazz
represents any class other than the class
Object
, then this function returns the object that
represents the superclass of the class specified by
clazz
.
If clazz
specifies the class Object
,
or clazz
represents an interface, this function
returns NULL
.
Index 10 in the JNIEnv interface function table.
env
: the JNI interface pointer.
clazz
: a Java class object.
Returns the superclass of the class represented by
clazz
, or NULL
.
jboolean IsAssignableFrom(JNIEnv *env, jclass
clazz1,
jclass clazz2);
Determines whether an object of clazz1
can be
safely cast to clazz2
.
Index 11 in the JNIEnv interface function table.
env
: the JNI interface pointer.
clazz1
: the first class argument.
clazz2
: the second class argument.
Returns JNI_TRUE
if either of the following is
true:
jint Throw(JNIEnv *env, jthrowable obj);
Causes a java.lang.Throwable
object to be
thrown.
Index 13 in the JNIEnv interface function table.
env
: the JNI interface pointer.
obj
: a java.lang.Throwable
object.
Returns 0 on success; a negative value on failure.
the java.lang.Throwable
object
obj
.
jint ThrowNew(JNIEnv *env, jclass clazz,
const char *message);
Constructs an exception object from the specified class with the
message specified by message
and causes that exception
to be thrown.
Index 14 in the JNIEnv interface function table.
env
: the JNI interface pointer.
clazz
: a subclass of
java.lang.Throwable
.
message
: the message used to construct the
java.lang.Throwable
object.
Returns 0 on success; a negative value on failure.
the newly constructed java.lang.Throwable
object.
jthrowable ExceptionOccurred(JNIEnv *env);
Determines if an exception is being thrown. The exception stays
being thrown until either the native code calls
ExceptionClear()
, or the Java code handles the
exception.
Index 15 in the JNIEnv interface function table.
env
: the JNI interface pointer.
Returns the exception object that is currently in the process of
being thrown, or NULL
if no exception is currently
being thrown.
void ExceptionDescribe(JNIEnv *env);
Prints an exception and a backtrace of the stack to a system
error-reporting channel, such as stderr
. This is a
convenience routine provided for debugging.
Index 16 in the JNIEnv interface function table.
env
: the JNI interface pointer.
void ExceptionClear(JNIEnv *env);
Clears any exception that is currently being thrown. If no exception is currently being thrown, this routine has no effect.
Index 17 in the JNIEnv interface function table.
env
: the JNI interface pointer.
void FatalError(JNIEnv *env, const char *msg);
Raises a fatal error and does not expect the VM to recover. This function does not return.
Index 18 in the JNIEnv interface function table.
env
: the JNI interface pointer.
msg
: an error message.
jboolean
ExceptionCheck(JNIEnv *env);
Returns JNI_TRUE
when there is a pending exception;
otherwise, returns JNI_FALSE
.
SDK/JRE 1.2
jobject NewGlobalRef(JNIEnv *env, jobject obj);
Creates a new global reference to the object referred to by the
obj
argument. The obj
argument may be a
global or local reference. Global references must be explicitly
disposed of by calling DeleteGlobalRef()
.
Index 21 in the JNIEnv interface function table.
env
: the JNI interface pointer.
obj
: a global or local reference.
Returns a global reference, or NULL
if the system
runs out of memory.
void DeleteGlobalRef(JNIEnv *env, jobject
globalRef);
Deletes the global reference pointed to by
globalRef
.
Index 22 in the JNIEnv interface function table.
env
: the JNI interface pointer.
globalRef
: a global reference.
Local references are valid for the duration of a native method call. They are freed automatically after the native method returns. Each local reference costs some amount of Java Virtual Machine resource. Programmers need to make sure that native methods do not excessively allocate local references. Although local references are automatically freed after the native method returns to Java, excessive allocation of local references may cause the VM to run out of memory during the execution of a native method.
void DeleteLocalRef(JNIEnv *env, jobject
localRef);
Deletes the local reference pointed to by
localRef
.
Index 23 in the JNIEnv interface function table.
env
: the JNI interface pointer.
localRef
: a local reference.
Note: SDK/JRE 1.1 provides the
The Java 2 SDK/JRE 1.2 and higher versions provide an additional set of functions for local reference lifetime management. They are the four functions listed below. |
jint EnsureLocalCapacity(JNIEnv *env, jint
capacity);
Ensures that at least a given number of local
references can be created in the current thread. Returns 0 on
success; otherwise returns a negative number and throws an
OutOfMemoryError
.
Before it enters a native method, the VM automatically ensures that at least 16 local references can be created.
For backward compatibility, the VM allocates local references
beyond the ensured capacity. (As a debugging support, the VM may
give the user warnings that too many local references are being
created. In the Java 2 SDK, the programmer can supply the
-verbose:jni
command line option to turn on these
messages.) The VM calls FatalError
if no more local
references can be created beyond the ensured capacity.
SDK/JRE 1.2
jint
PushLocalFrame(JNIEnv *env, jint capacity);
Creates a new local reference frame, in which at least a given
number of local references can be created. Returns 0 on success, a
negative number and a pending OutOfMemoryError
on
failure.
Note that local references already created in previous local frames are still valid in the current local frame.
SDK/JRE 1.2
jobject
PopLocalFrame(JNIEnv *env, jobject result);
Pops off the current local reference frame, frees all the local
references, and returns a local reference in the previous local
reference frame for the given result
object.
Pass NULL
as result
if you do not need
to return a reference to the previous frame.
SDK/JRE 1.2
jobject
NewLocalRef(JNIEnv *env, jobject ref);
Creates a new local reference that refers to the same object as
ref
. The given ref
may be a global or
local reference. Returns NULL
if ref
refers to null
.
SDK/JRE 1.2
NULL
. Programmers can
detect whether a weak global reference points to a freed object by
using IsSameObject
to compare the weak reference
against NULL
.
Weak global references in JNI are a simplified version of the
Java Weak References, available as part of the Java 2 Platform API
( java.lang.ref
package and its classes).
Clarification (added June 2001)
Since garbage collection may occur while native methods are
running, objects referred to by weak global references can be freed
at any time. While weak global references can be used where global
references are used, it is generally inappropriate to do so, as
they may become functionally equivalent to NULL
without notice.
While IsSameObject
can be used to
determine whether a weak global reference refers to a freed object,
it does not prevent the object from being freed immediately
thereafter. Consequently, programmers may not rely on this check to
determine whether a weak global reference may used (as a
non-NULL
reference) in any future JNI function
call.
To overcome this inherent limitation, it is recommended that
a standard (strong) local or global reference to the same object be
acquired using the JNI functions NewLocalRef
or NewGlobalRef
, and that this strong
reference be used to access the intended object. These functions
will return NULL
if the object has been freed,
and otherwise will return a strong reference (which will prevent
the object from being freed). The new reference should be
explicitly deleted when immediate access to the object is no longer
required, allowing the object to be freed.
The weak global reference is weaker than other types of weak
references (Java objects of the SoftReference or WeakReference
classes). A weak global reference to a specific object will not
become functionally equivalent to NULL
until
after SoftReference or WeakReference objects referring to that same
specific object have had their references cleared.
The weak global reference is weaker than Java's internal
references to objects requiring finalization. A weak global
reference will not become functionally equivalent to
NULL
until after the completion of the finalizer
for the referenced object, if present.
Interactions between weak global references and PhantomReferences are undefined. In particular, implementations of a Java VM may (or may not) process weak global references after PhantomReferences, and it may (or may not) be possible to use weak global references to hold on to objects which are also referred to by PhantomReference objects. This undefined use of weak global references should be avoided.
jweak NewWeakGlobalRef(JNIEnv *env, jobject
obj);
Creates a new weak global reference. Returns NULL
if obj
refers to null
, or if the VM runs
out of memory. If the VM runs out of memory, an
OutOfMemoryError
will be thrown.
SDK/JRE 1.2
void DeleteWeakGlobalRef(JNIEnv *env, jweak
obj);
Delete the VM resources needed for the given weak global reference.
jobject AllocObject(JNIEnv *env, jclass clazz);
Allocates a new Java object without invoking any of the constructors for the object. Returns a reference to the object.
The clazz argument must not refer to an array class.
Index 27 in the JNIEnv interface function table.
env
: the JNI interface pointer.
clazz
: a Java class object.
Returns a Java object, or NULL
if the object cannot
be constructed.
InstantiationException
: if the class is an
interface or an abstract class.
OutOfMemoryError
: if the system runs out of
memory.
jobject NewObject(JNIEnv *env, jclass clazz,
jmethodID methodID, ...);
jobject NewObjectA(JNIEnv *env, jclass clazz,
jmethodID methodID, jvalue *args);
jobject NewObjectV(JNIEnv *env, jclass clazz,
jmethodID methodID, va_list args);
Constructs a new Java object. The method ID indicates which
constructor method to invoke. This ID must be obtained by calling
GetMethodID()
with <init>
as the
method name and void
(V
) as the return
type.
The clazz
argument must not refer to an array
class.
Programmers place all arguments that are to be passed to the
constructor immediately following the methodID
argument. NewObject()
accepts these arguments and
passes them to the Java method that the programmer wishes to
invoke.
Index 28 in the JNIEnv interface function table.
Programmers place all arguments that are to be passed to the
constructor in an args
array of jvalues
that immediately follows the methodID
argument.
NewObjectA()
accepts the arguments in this array, and,
in turn, passes them to the Java method that the programmer wishes
to invoke.
Index 30 in the JNIEnv interface function table.
Programmers place all arguments that are to be passed to the
constructor in an args
argument of type
va_list
that immediately follows the
methodID
argument. NewObjectV()
accepts
these arguments, and, in turn, passes them to the Java method that
the programmer wishes to invoke.
Index 29 in the JNIEnv interface function table.
env
: the JNI interface pointer.
clazz
: a Java class object.
methodID
: the method ID of the constructor.
arguments to the constructor.
args
: an array of arguments to the constructor.
args
: a va_list of arguments to the
constructor.
Returns a Java object, or NULL
if the object cannot
be constructed.
InstantiationException
: if the class is an
interface or an abstract class.
OutOfMemoryError
: if the system runs out of
memory.
Any exceptions thrown by the constructor.
jclass GetObjectClass(JNIEnv *env, jobject
obj);
Returns the class of an object.
Index 31 in the JNIEnv interface function table.
env
: the JNI interface pointer.
obj
: a Java object (must not be
NULL
).
Returns a Java class object.
jobjectRefType GetObjectRefType(JNIEnv* env, jobject
obj);
Returns the type of the object referred to by the
obj
argument. The argument obj
can either
be a local, global or weak global reference.
Index 232 in the JNIEnv interface function table.
env
: the JNI interface pointer.
obj
: a local, global or weak global
reference.
vm
: the virtual machine instance from which the
interface will be retrieved.
env
: pointer to the location where the JNI interface
pointer for the current thread will be placed.
version
: the requested JNI version.
The function GetObjectRefType
returns one of the
following enumerated values defined as a
jobjectRefType
:
JNIInvalidRefType = 0,
JNILocalRefType = 1,
JNIGlobalRefType = 2,
JNIWeakGlobalRefType = 3
If the argument obj
is a weak global reference
type, the return will be JNIWeakGlobalRefType
.
If the argument obj
is a global reference type, the
return value will be JNIGlobalRefType
.
If the argument obj
is a local reference type, the
return will be JNILocalRefType
.
If the obj
argument is not a valid reference, the
return value for this function will be
JNIInvalidRefType
.
An invalid reference is a reference which is not a valid handle.
That is, the obj
pointer address does not point to a
location in memory which has been allocated from one of the Ref
creation functions or returned from a JNI function.
As such, NULL
would be an invalid reference and
GetObjectRefType(env,NULL)
would return
JNIInvalidRefType
.
On the other hand, a null reference, which is a reference that points to a null, would return the type of reference that the null reference was originally created as.
GetObjectRefType
cannot be used on deleted
references.
Since references are typically implemented as pointers to memory
data structures that can potentially be reused by any of the
reference allocation services in the VM, once deleted, it is not
specified what value the GetObjectRefType
will
return.
jboolean IsInstanceOf(JNIEnv *env, jobject obj,
jclass clazz);
Tests whether an object is an instance of a class.
Index 32 in the JNIEnv interface function table.
env
: the JNI interface pointer.
obj
: a Java object.
clazz
: a Java class object.
Returns JNI_TRUE
if obj
can be cast to
clazz
; otherwise, returns JNI_FALSE
. A
NULL
object can be cast to any class.
jboolean IsSameObject(JNIEnv *env, jobject ref1,
jobject ref2);
Tests whether two references refer to the same Java object.
Index 24 in the JNIEnv interface function table.
env
: the JNI interface pointer.
ref1
: a Java object.
ref2
: a Java object.
Returns JNI_TRUE
if ref1
and
ref2
refer to the same Java object, or are both
NULL
; otherwise, returns JNI_FALSE
.
jfieldID GetFieldID(JNIEnv *env, jclass clazz,
const char *name, const char *sig);
Returns the field ID for an instance (nonstatic) field of a class. The field is specified by its name and signature. The Get<type>Field and Set<type>Field families of accessor functions use field IDs to retrieve object fields.
GetFieldID()
causes an uninitialized class to be
initialized.
GetFieldID()
cannot be used to obtain the length
field of an array. Use GetArrayLength()
instead.
Index 94 in the JNIEnv interface function table.
env
: the JNI interface pointer.
clazz
: a Java class object.
name
: the field name in a 0-terminated UTF-8
string.
sig
: the field signature in a 0-terminated UTF-8
string.
Returns a field ID, or NULL
if the operation
fails.
NoSuchFieldError
: if the specified field cannot be
found.
ExceptionInInitializerError
: if the class
initializer fails due to an exception.
OutOfMemoryError
: if the system runs out of
memory.
NativeType Get<type>Field(JNIEnv
*env, jobject obj,
jfieldID fieldID);
This family of accessor routines returns the value of an
instance (nonstatic) field of an object. The field to access is
specified by a field ID obtained by calling
GetFieldID()
.
The following table describes the Get<type>Field routine name and result type. You should replace type in Get<type>Field with the Java type of the field, or use one of the actual routine names from the table, and replace NativeType with the corresponding native type for that routine.
Table 4-1a Get<type>Field Family of Accessor RoutinesGet<type>Field Routine Name | Native Type |
---|---|
GetObjectField() |
jobject |
GetBooleanField() |
jboolean |
GetByteField() |
jbyte |
GetCharField() |
jchar |
GetShortField() |
jshort |
GetIntField() |
jint |
GetLongField() |
jlong |
GetFloatField() |
jfloat |
GetDoubleField() |
jdouble |
Get<type>Field Routine Name | Index |
---|---|
GetObjectField() |
95 |
GetBooleanField() |
96 |
GetByteField() |
97 |
GetCharField() |
98 |
GetShortField() |
99 |
GetIntField() |
100 |
GetLongField() |
101 |
GetFloatField() |
102 |
GetDoubleField() |
103 |
env
: the JNI interface pointer.
obj
: a Java object (must not be
NULL
).
fieldID
: a valid field ID.
Returns the content of the field.
void
Set<type>Field(JNIEnv
*env, jobject obj, jfieldID fieldID,
NativeType value);
This family of accessor routines sets the value of an instance
(nonstatic) field of an object. The field to access is specified by
a field ID obtained by calling GetFieldID()
.
The following table describes the Set<type>Field routine name and value type. You should replace type in Set<type>Field with the Java type of the field, or use one of the actual routine names from the table, and replace NativeType with the corresponding native type for that routine.
Table 4-2a Set<type>Field Family of Accessor RoutinesSet<type>Field Routine | Native Type |
---|---|
SetObjectField() |
jobject |
SetBooleanField() |
jboolean |
SetByteField() |
jbyte |
SetCharField() |
jchar |
SetShortField() |
jshort |
SetIntField() |
jint |
SetLongField() |
jlong |
SetFloatField() |
jfloat |
SetDoubleField() |
jdouble |
Indices in the JNIEnv interface function table.
Table 4-2b Set<type>Field Family of Accessor RoutinesSet<type>Field Routine | Index |
---|---|
SetObjectField() |
104 |
SetBooleanField() |
105 |
SetByteField() |
106 |
SetCharField() |
107 |
SetShortField() |
108 |
SetIntField() |
109 |
SetLongField() |
110 |
SetFloatField() |
111 |
SetDoubleField() |
112 |
env
: the JNI interface pointer.
obj
: a Java object (must not be
NULL
).
fieldID
: a valid field ID.
value
: the new value of the field.
jmethodID GetMethodID(JNIEnv *env, jclass clazz,
const char *name, const char *sig);
Returns the method ID for an instance (nonstatic) method of a
class or interface. The method may be defined in one of the
clazz
's superclasses and inherited by
clazz
. The method is determined by its name and
signature.
GetMethodID()
causes an uninitialized class to be
initialized.
To obtain the method ID of a constructor, supply
<init>
as the method name and void
(V
) as the return type.
Index 33 in the JNIEnv interface function table.
env
: the JNI interface pointer.
clazz
: a Java class object.
name
: the method name in a 0-terminated UTF-8
string.
sig
: the method signature in 0-terminated UTF-8
string.
Returns a method ID, or NULL
if the specified
method cannot be found.
NoSuchMethodError
: if the specified method cannot
be found.
ExceptionInInitializerError
: if the class
initializer fails due to an exception.
OutOfMemoryError
: if the system runs out of
memory.
NativeType Call<type>Method(JNIEnv
*env, jobject obj,
jmethodID methodID, ...);
NativeType
Call<type>MethodA(JNIEnv *env, jobject
obj,
jmethodID methodID, jvalue *args);
NativeType
Call<type>MethodV(JNIEnv *env, jobject
obj,
jmethodID methodID, va_list args);
Methods from these three families of operations are used to call a Java instance method from a native method.They only differ in their mechanism for passing parameters to the methods that they call.
These families of operations invoke an instance (nonstatic)
method on a Java object, according to the specified method ID. The
methodID
argument must be obtained by calling
GetMethodID
()
.
When these functions are used to call private methods and
constructors, the method ID must be derived from the real class of
obj
, not from one of its superclasses.
Programmers place all arguments that are to be passed to the
method immediately following the methodID
argument.
The Call<type>Method routine accepts these arguments
and passes them to the Java method that the programmer wishes to
invoke.
Programmers place all arguments to the method in an
args
array of jvalues
that immediately
follows the methodID
argument. The
Call<type>MethodA routine accepts the arguments in
this array, and, in turn, passes them to the Java method that the
programmer wishes to invoke.
Programmers place all arguments to the method in an
args
argument of type va_list
that
immediately follows the methodID
argument. The
Call<type>MethodV routine accepts the arguments,
and, in turn, passes them to the Java method that the programmer
wishes to invoke.
The following table describes each of the method calling routines according to their result type. You should replace type in Call<type>Method with the Java type of the method you are calling (or use one of the actual method calling routine names from the table) and replace NativeType with the corresponding native type for that routine.
Table 4-3a Instance Method Calling RoutinesCall<type>Method Routine Name | Native Type |
---|---|
CallVoidMethod()
CallVoidMethodA() CallVoidMethodV() |
void |
CallObjectMethod()
CallObjectMethodA()
CallObjectMethodV() |
jobject |
CallBooleanMethod()
CallBooleanMethodA()
CallBooleanMethodV() |
jboolean |
CallByteMethod()
CallByteMethodA() CallByteMethodV() |
jbyte |
CallCharMethod()
CallCharMethodA() CallCharMethodV() |
jchar |
CallShortMethod()
CallShortMethodA()
CallShortMethodV() |
jshort |
CallIntMethod()
CallIntMethodA() CallIntMethodV() |
jint |
CallLongMethod()
CallLongMethodA() CallLongMethodV() |
jlong |
CallFloatMethod()
CallFloatMethodA()
CallFloatMethodV() |
jfloat |
CallDoubleMethod()
CallDoubleMethodA()
CallDoubleMethodV() |
jdouble |
Indices in the JNIEnv interface function table:
Table 4-3b Instance Method Calling RoutinesCall<type>Method Routine Name | Index |
---|---|
CallVoidMethod()
CallVoidMethodA() CallVoidMethodV() |
61 |
CallObjectMethod()
CallObjectMethodA()
CallObjectMethodV() |
34 |
CallBooleanMethod()
CallBooleanMethodA()
CallBooleanMethodV() |
37 |
CallByteMethod()
CallByteMethodA() CallByteMethodV() |
40 |
CallCharMethod()
CallCharMethodA() CallCharMethodV() |
43 |
CallShortMethod()
CallShortMethodA()
CallShortMethodV() |
46 |
CallIntMethod()
CallIntMethodA() CallIntMethodV() |
49 |
CallLongMethod()
CallLongMethodA() CallLongMethodV() |
52 |
CallFloatMethod()
CallFloatMethodA()
CallFloatMethodV() |
55 |
CallDoubleMethod()
CallDoubleMethodA()
CallDoubleMethodV() |
58 |
env
: the JNI interface pointer.
obj
: a Java object.
methodID
: a method ID.
arguments to the Java method.
args
: an array of arguments.
args
: a va_list of arguments.
Returns the result of calling the Java method.
Exceptions raised during the execution of the Java
method.
NativeType
CallNonvirtual<type>Method(JNIEnv *env,
jobject obj,
jclass clazz, jmethodID methodID, ...);
NativeType
CallNonvirtual<type>MethodA(JNIEnv *env,
jobject obj,
jclass clazz, jmethodID methodID, jvalue *args);
NativeType
CallNonvirtual<type>MethodV(JNIEnv *env,
jobject obj,
jclass clazz, jmethodID methodID, va_list args);
These families of operations invoke an instance (nonstatic)
method on a Java object, according to the specified class and
method ID. The methodID
argument must be obtained by
calling GetMethodID
()
on the class
clazz
.
The CallNonvirtual<type>Method families of
routines and the Call<type>Method families of
routines are different. Call<type>Method routines
invoke the method based on the class of the object, while
CallNonvirtual<type>Method routines invoke the
method based on the class, designated by the clazz
parameter, from which the method ID is obtained. The method ID must
be obtained from the real class of the object or from one of its
superclasses.
Programmers place all arguments that are to be passed to the
method immediately following the methodID
argument.
The CallNonvirtual<type>Method routine accepts these
arguments and passes them to the Java method that the programmer
wishes to invoke.
Programmers place all arguments to the method in an
args
array of jvalues
that immediately
follows the methodID
argument. The
CallNonvirtual<type>MethodA routine accepts the
arguments in this array, and, in turn, passes them to the Java
method that the programmer wishes to invoke.
Programmers place all arguments to the method in an
args
argument of type va_list
that
immediately follows the methodID
argument. The
CallNonvirtualMethodV routine accepts the arguments, and,
in turn, passes them to the Java method that the programmer wishes
to invoke.
The following table describes each of the method calling routines according to their result type. You should replace type in CallNonvirtual<type>Method with the Java type of the method, or use one of the actual method calling routine names from the table, and replace NativeType with the corresponding native type for that routine.
Table 4-4a CallNonvirtual<type>Method Routines
CallNonvirtual<type>Method Routine Name | Native Type |
---|---|
CallNonvirtualVoidMethod()
CallNonvirtualVoidMethodA()
CallNonvirtualVoidMethodV() |
void |
CallNonvirtualObjectMethod()
CallNonvirtualObjectMethodA()
CallNonvirtualObjectMethodV() |
jobject |
CallNonvirtualBooleanMethod()
CallNonvirtualBooleanMethodA()
CallNonvirtualBooleanMethodV() |
jboolean |
CallNonvirtualByteMethod()
CallNonvirtualByteMethodA()
CallNonvirtualByteMethodV() |
jbyte |
CallNonvirtualCharMethod()
CallNonvirtualCharMethodA()
CallNonvirtualCharMethodV() |
jchar |
CallNonvirtualShortMethod()
CallNonvirtualShortMethodA()
CallNonvirtualShortMethodV() |
jshort |
CallNonvirtualIntMethod()
CallNonvirtualIntMethodA()
CallNonvirtualIntMethodV() |
jint |
CallNonvirtualLongMethod()
CallNonvirtualLongMethodA()
CallNonvirtualLongMethodV() |
jlong |
CallNonvirtualFloatMethod()
CallNonvirtualFloatMethodA()
CallNonvirtualFloatMethodV() |
jfloat |
CallNonvirtualDoubleMethod()
CallNonvirtualDoubleMethodA()
CallNonvirtualDoubleMethodV() |
jdouble |
Indices in the JNIEnv interface function table.
Table 4-4b CallNonvirtual<type>Method RoutinesCallNonvirtual<type>Method Routine Name | Index |
---|---|
CallNonvirtualVoidMethod()
CallNonvirtualVoidMethodA()
CallNonvirtualVoidMethodV() |
91 93 92 |
CallNonvirtualObjectMethod()
CallNonvirtualObjectMethodA()
CallNonvirtualObjectMethodV() |
64 66 65 |
CallNonvirtualBooleanMethod()
CallNonvirtualBooleanMethodA()
CallNonvirtualBooleanMethodV() |
67 69 68 |
CallNonvirtualByteMethod()
CallNonvirtualByteMethodA()
CallNonvirtualByteMethodV() |
70 72 71 |
CallNonvirtualCharMethod()
CallNonvirtualCharMethodA()
CallNonvirtualCharMethodV() |
73 75 74 |
CallNonvirtualShortMethod()
CallNonvirtualShortMethodA()
CallNonvirtualShortMethodV() |
76 78 77 |
CallNonvirtualIntMethod()
CallNonvirtualIntMethodA()
CallNonvirtualIntMethodV() |
79 81 80 |
CallNonvirtualLongMethod()
CallNonvirtualLongMethodA()
CallNonvirtualLongMethodV() |
82 84 83 |
CallNonvirtualFloatMethod()
CallNonvirtualFloatMethodA()
CallNonvirtualFloatMethodV() |
85 87 86 |
CallNonvirtualDoubleMethod()
CallNonvirtualDoubleMethodA()
CallNonvirtualDoubleMethodV() |
88 90 89 |
env
: the JNI interface pointer.
clazz:
a
Java class.
obj
: a Java object.
methodID
: a method ID.
arguments to the Java method.
args
: an array of arguments.
args
: a va_list
of arguments.
Returns the result of calling the Java method.
Exceptions raised during the execution of the Java method.
jfieldID GetStaticFieldID(JNIEnv *env, jclass clazz,
const char *name, const char *sig);
Returns the field ID for a static field of a class. The field is specified by its name and signature. The GetStatic<type>Field and SetStatic<type>Field families of accessor functions use field IDs to retrieve static fields.
GetStaticFieldID()
causes an uninitialized class to
be initialized.
Index 144 in the JNIEnv interface function table.
env
: the JNI interface pointer.
clazz
: a Java class object.
name
: the static field name in a 0-terminated UTF-8
string.
sig
: the field signature in a 0-terminated UTF-8
string.
Returns a field ID, or NULL
if the specified static
field cannot be found.
NoSuchFieldError
: if the specified static field
cannot be found.
ExceptionInInitializerError
: if the class
initializer fails due to an exception.
OutOfMemoryError
: if the system runs out of
memory.
NativeType
GetStatic<type>Field(JNIEnv *env, jclass
clazz,
jfieldID fieldID);
This family of accessor routines returns the value of a static
field of an object. The field to access is specified by a field ID,
which is obtained by calling GetStaticFieldID()
.
The following table describes the family of get routine names and result types. You should replace type in GetStatic<type>Field with the Java type of the field, or one of the actual static field accessor routine names from the table, and replace NativeType with the corresponding native type for that routine.
Table 4-5a GetStatic<type>Field Family of Accessor RoutinesGetStatic<type>Field Routine Name | Native Type |
---|---|
GetStaticObjectField () |
jobject |
GetStaticBooleanField () |
jboolean |
GetStaticByteField () |
jbyte |
GetStaticCharField () |
jchar |
GetStaticShortField () |
jshort |
GetStaticIntField () |
jint |
GetStaticLongField () |
jlong |
GetStaticFloatField () |
jfloat |
GetStaticDoubleField () |
jdouble |
Indices in the JNIEnv interface function table.
Table 4-5b GetStatic<type>Field Family of Accessor RoutinesGetStatic<type>Field Routine Name | Index |
---|---|
GetStaticObjectField () |
145 |
GetStaticBooleanField () |
146 |
GetStaticByteField () |
147 |
GetStaticCharField () |
148 |
GetStaticShortField () |
149 |
GetStaticIntField () |
150 |
GetStaticLongField () |
151 |
GetStaticFloatField () |
152 |
GetStaticDoubleField () |
153 |
env
: the JNI interface pointer.
clazz
: a Java class object.
fieldID
: a static field ID.
Returns the content of the static field.
void
SetStatic<type>Field(JNIEnv *env, jclass
clazz,
NativeType
jfieldID fieldID,value);
This family of accessor routines sets the value of a static
field of an object. The field to access is specified by a field ID,
which is obtained by calling GetStaticFieldID()
.
The following table describes the set routine name and value types. You should replace type in SetStatic<type>Field with the Java type of the field, or one of the actual set static field routine names from the table, and replace NativeType with the corresponding native type for that routine.
Table 4-6a SetStatic<type>Field Family of Accessor RoutinesSetStatic<type>Field Routine Name | NativeType |
---|---|
SetStaticObjectField () |
jobject |
SetStaticBooleanField () |
jboolean |
SetStaticByteField () |
jbyte |
SetStaticCharField () |
jchar |
SetStaticShortField () |
jshort |
SetStaticIntField () |
jint |
SetStaticLongField () |
jlong |
SetStaticFloatField () |
jfloat |
SetStaticDoubleField () |
jdouble |
Indices in the JNIEnv interface function table.
Table 4-6b SetStatic<type>Field Family of Accessor RoutinesSetStatic<type>Field Routine Name | Index |
---|---|
SetStaticObjectField () |
154 |
SetStaticBooleanField () |
155 |
SetStaticByteField () |
156 |
SetStaticCharField () |
157 |
SetStaticShortField () |
158 |
SetStaticIntField () |
159 |
SetStaticLongField () |
160 |
SetStaticFloatField () |
161 |
SetStaticDoubleField () |
162 |
env
: the JNI interface pointer.
clazz
: a Java class object.
fieldID
: a static field ID.
value
: the new value of the field.
jmethodID GetStaticMethodID(JNIEnv *env, jclass
clazz,
const char *name, const char *sig);
Returns the method ID for a static method of a class. The method is specified by its name and signature.
GetStaticMethodID()
causes an uninitialized class
to be initialized.
env
: the JNI interface pointer.
clazz
: a Java class object.
name
: the static method name in a 0-terminated
UTF-8 string.
sig
: the method signature in a 0-terminated UTF-8
string.
Returns a method ID, or NULL
if the operation
fails.
NoSuchMethodError
: if the specified static method
cannot be found.
ExceptionInInitializerError
: if the class
initializer fails due to an exception.
OutOfMemoryError
: if the system runs out of
memory.
NativeType
CallStatic<type>Method(JNIEnv *env, jclass
clazz,
jmethodID methodID, ...);
NativeType
CallStatic<type>MethodA(JNIEnv *env, jclass
clazz,
jmethodID methodID, jvalue *args);
NativeType
CallStatic<type>MethodV(JNIEnv *env, jclass
clazz,
jmethodID methodID, va_list args);
This family of operations invokes a static method on a Java
object, according to the specified method ID. The
methodID
argument must be obtained by calling
GetStaticMethodID
()
.
The method ID must be derived from clazz
, not from
one of its superclasses.
Programmers should place all arguments that are to be passed to
the method immediately following the methodID
argument. The CallStatic<type>Method routine accepts
these arguments and passes them to the Java method that the
programmer wishes to invoke.
Programmers should place all arguments to the method in an
args
array of jvalues
that immediately
follows the methodID
argument. The
CallStaticMethodA routine accepts the arguments in this
array, and, in turn, passes them to the Java method that the
programmer wishes to invoke.
Programmers should place all arguments to the method in an
args
argument of type va_list
that
immediately follows the methodID
argument. The
CallStaticMethodV routine accepts the arguments, and, in
turn, passes them to the Java method that the programmer wishes to
invoke.
The following table describes each of the method calling routines according to their result types. You should replace type in CallStatic<type>Method with the Java type of the method, or one of the actual method calling routine names from the table, and replace NativeType with the corresponding native type for that routine.
Table 4-7a CallStatic<type>Method Calling RoutinesCallStatic<type>Method Routine Name | Native Type |
---|---|
CallStaticVoidMethod ()
CallStaticVoidMethodA ()
CallStaticVoidMethod V() |
void |
CallStaticObjectMethod ()
CallStaticObjectMethod A()
CallStaticObjectMethod V() |
jobject |
CallStaticBooleanMethod ()
CallStaticBooleanMethod A()
CallStaticBooleanMethod V() |
jboolean |
CallStaticByteMethod ()
CallStaticByteMethod A()
CallStaticByteMethod V() |
jbyte |
CallStaticCharMethod ()
CallStaticCharMethod A()
CallStaticCharMethod V() |
jchar |
CallStaticShortMethod ()
CallStaticShortMethod A()
CallStaticShortMethod V() |
jshort |
CallStaticIntMethod ()
CallStaticIntMethod A()
CallStaticIntMethod V() |
jint |
CallStaticLongMethod ()
CallStaticLongMethod A()
CallStaticLongMethod V() |
jlong |
CallStaticFloatMethod ()
CallStaticFloatMethod A()
CallStaticFloatMethod V() |
jfloat |
CallStaticDoubleMethod ()
CallStaticDoubleMethod A()
CallStaticDoubleMethod V() |
jdouble |
Indices in the JNIEnv interface function table.
Table 4-7b CallStatic<type>Method Calling RoutinesCallStatic<type>Method Routine Name | Index |
---|---|
CallStaticVoidMethod ()
CallStaticVoidMethodA ()
CallStaticVoidMethod V() |
141 143 142 |
CallStaticObjectMethod ()
CallStaticObjectMethod A()
CallStaticObjectMethod V() |
114 116 115 |
CallStaticBooleanMethod ()
CallStaticBooleanMethod A()
CallStaticBooleanMethod V() |
117 119 118 |
CallStaticByteMethod ()
CallStaticByteMethod A()
CallStaticByteMethod V() |
120 122 121 |
CallStaticCharMethod ()
CallStaticCharMethod A()
CallStaticCharMethod V() |
123 125 124 |
CallStaticShortMethod ()
CallStaticShortMethod A()
CallStaticShortMethod V() |
126 128 127 |
CallStaticIntMethod ()
CallStaticIntMethod A()
CallStaticIntMethod V() |
129 131 130 |
CallStaticLongMethod ()
CallStaticLongMethod A()
CallStaticLongMethod V() |
132 134 133 |
CallStaticFloatMethod ()
CallStaticFloatMethod A()
CallStaticFloatMethod V() |
135 137 136 |
CallStaticDoubleMethod ()
CallStaticDoubleMethod A()
CallStaticDoubleMethod V() |
138 140 139 |
env
: the JNI interface pointer.
clazz
: a Java class object.
methodID
: a static method ID.
arguments to the static method.
args
: an array of arguments.
args
: a va_list
of arguments.
Returns the result of calling the static Java method.
Exceptions raised during the execution of the Java
method.
jstring NewString(JNIEnv *env, const jchar
*unicodeChars,
jsize len);
Constructs a new java.lang.String
object from an
array of Unicode characters.
env
: the JNI interface pointer.
unicodeChars
: pointer to a Unicode string.
len
: length of the Unicode string.
Returns a Java string object, or NULL
if the string
cannot be constructed.
OutOfMemoryError
: if the system runs out of
memory.
jsize GetStringLength(JNIEnv *env, jstring
string);
Returns the length (the count of Unicode characters) of a Java string.
env
: the JNI interface pointer.
string
: a Java string object.
Returns the length of the Java string.
const jchar * GetStringChars(JNIEnv *env, jstring
string,
jboolean *isCopy);
Returns a pointer to the array of Unicode characters of the
string. This pointer is valid until
ReleaseStringchars()
is called.
If isCopy
is not NULL
, then
*isCopy
is set to JNI_TRUE
if a copy is
made; or it is set to JNI_FALSE
if no copy is
made.
env
: the JNI interface pointer.
string
: a Java string object.
isCopy
: a pointer to a boolean.
Returns a pointer to a Unicode string, or NULL
if
the operation fails.
void ReleaseStringChars(JNIEnv *env, jstring string,
const jchar *chars);
Informs the VM that the native code no longer needs access to
chars
. The chars
argument is a pointer
obtained from string
using
GetStringChars()
.
env
: the JNI interface pointer.
string
: a Java string object.
chars
: a pointer to a Unicode string.
jstring NewStringUTF(JNIEnv *env, const char
*bytes);
Constructs a new java.lang.String
object from an
array of UTF-8 characters.
env
: the JNI interface pointer.
bytes
: the pointer to a UTF-8 string.
Returns a Java string object, or NULL
if the string
cannot be constructed.
OutOfMemoryError
: if the system runs out of
memory.
jsize GetStringUTFLength(JNIEnv *env, jstring
string);
Returns the UTF-8 length in bytes of a string.
env
: the JNI interface pointer.
string
: a Java string object.
Returns the UTF-8 length of the string.
const jbyte* GetStringUTFChars(JNIEnv *env, jstring
string,
jboolean *isCopy);
Returns a pointer to an array of UTF-8 characters of the string.
This array is valid until it is released by
ReleaseStringUTFChars()
.
If isCopy
is not NULL
, then
*isCopy
is set to JNI_TRUE
if a copy is
made; or it is set to JNI_FALSE
if no copy is
made.
env
: the JNI interface pointer.
string
: a Java string object.
isCopy
: a pointer to a boolean.
Returns a pointer to a UTF-8 string, or NULL
if the
operation fails.
void ReleaseStringUTFChars(JNIEnv *env, jstring
string,
const char *utf);
Informs the VM that the native code no longer needs access to
utf
. The utf
argument is a pointer
derived from string
using
GetStringUTFChars()
.
env
: the JNI interface pointer.
string
: a Java string object.
utf
: a pointer to a UTF-8 string.
Note: In SKD/JRE 1.1, programmers can get primitive array elements in a user-supplied buffer. Java 2 SDK/JRE 1.2 and higher versions allow native code to obtain Unicode or UTF-8 characters in a user-supplied buffer. See the functions below. |
void GetStringRegion(JNIEnv *env, jstring str, jsize
start, jsize len, jchar *buf);
Copies len
number of Unicode characters beginning
at offset start
to the given buffer
buf
.
Throws StringIndexOutOfBoundsException
on index
overflow.
SDK/JRE 1.2
< void GetStringUTFRegion(JNIEnv *env, jstring str,
jsize start, jsize len, char *buf);
Translates len
number of Unicode characters
beginning at offset start
into UTF-8 format and place
the result in the given buffer buf
.
Throws StringIndexOutOfBoundsException
on index
overflow.
SDK/JRE 1.2
ReleaseStringCriticalconst jchar * GetStringCritical(JNIEnv *env, jstring
string, jboolean *isCopy);
void ReleaseStringCritical(JNIEnv *env, jstring string, const jchar
*carray);
The semantics of these two functions are similar to the existing
Get/ReleaseStringChars
functions. If possible, the VM
returns a pointer to string elements; otherwise, a copy is made.
However, there are significant restrictions on how these
functions can be used. In a code segment enclosed by
Get/ReleaseStringCritical
calls, the native code must
not issue arbitrary JNI calls, or cause the current thread to
block.
The restrictions on Get/ReleaseStringCritical
are
similar to those on
Get/ReleasePrimitiveArrayCritical
.
SDK/JRE 1.2
jsize GetArrayLength(JNIEnv *env, jarray
array);
Returns the number of elements in the array.
env
: the JNI interface pointer.
array
: a Java array object.
Returns the length of the array.
jobjectArray NewObjectArray(JNIEnv *env, jsize
length,
jclass elementClass, jobject initialElement);
Constructs a new array holding objects in class
elementClass
. All elements are initially set to
initialElement
.
env
: the JNI interface pointer.
length
: array size.
elementClass
: array element class.
initialElement
: initialization value.
Returns a Java array object, or NULL
if the array
cannot be constructed.
OutOfMemoryError
: if the system runs out of
memory.
jobject GetObjectArrayElement(JNIEnv *env,
jobjectArray array, jsize index);
Returns an element of an Object
array.
env
: the JNI interface pointer.
array
: a Java array.
index
: array index.
Returns a Java object.
ArrayIndexOutOfBoundsException
: if
index
does not specify a valid index in the array.
void SetObjectArrayElement(JNIEnv *env, jobjectArray
array,
jsize index, jobject value);
Sets an element of an Object
array.
env
: the JNI interface pointer.
array
: a Java array.
index
: array index.
value
: the new value.
ArrayIndexOutOfBoundsException
: if
index
does not specify a valid index in the array.
ArrayStoreException
: if the class of
value
is not a subclass of the element class of the
array.
ArrayType
New<PrimitiveType>Array(JNIEnv *env, jsize
length);
A family of operations used to construct a new primitive array object. Table 4-8 describes the specific primitive array constructors. You should replace New<PrimitiveType>Array with one of the actual primitive array constructor routine names from the following table, and replace ArrayType with the corresponding array type for that routine.
Table 4-8a New<PrimitiveType>Array Family of Array ConstructorsNew<PrimitiveType>Array Routines | Array Type |
---|---|
NewBooleanArray() |
jbooleanArray |
NewByteArray() |
jbyteArray |
NewCharArray() |
jcharArray |
NewShortArray() |
jshortArray |
NewIntArray() |
jintArray |
NewLongArray() |
jlongArray |
NewFloatArray() |
jfloatArray |
NewDoubleArray() |
jdoubleArray |
Indices in the JNIEnv interface function table.
Table 4-8b New<PrimitiveType>Array Family of Array ConstructorsNew<PrimitiveType>Array Routines | Index |
---|---|
NewBooleanArray() |
175 |
NewByteArray() |
176 |
NewCharArray() |
177 |
NewShortArray() |
178 |
NewIntArray() |
179 |
NewLongArray() |
180 |
NewFloatArray() |
181 |
NewDoubleArray() |
182 |
env
: the JNI interface pointer.
length
: the array length.
Returns a Java array, or NULL
if the array cannot
be constructed.
NativeType
*
Get<PrimitiveType>ArrayElements(JNIEnv
*env,
ArrayType
array, jboolean
*isCopy);
A family of functions that returns the body of the primitive
array. The result is valid until the corresponding
Release<
PrimitiveType>
ArrayElements()
function is called. Since the returned array may be a copy of
the Java array, changes made to the returned array will not
necessarily be reflected in the original array
until
Release<PrimitiveType>ArrayElements()
is
called.
If isCopy
is not NULL
, then
*isCopy
is set to JNI_TRUE
if a copy is
made; or it is set to JNI_FALSE
if no copy is
made.
The following table describes the specific primitive array element accessors. You should make the following substitutions:
Regardless of how boolean arrays are represented in the Java VM,
GetBooleanArrayElements()
always returns a pointer to
jbooleans
, with each byte denoting an element (the
unpacked representation). All arrays of other types are guaranteed
to be contiguous in memory.
Get<PrimitiveType>ArrayElements Routines | Array Type | Native Type |
---|---|---|
GetBooleanArrayElements() |
jbooleanArray | jboolean |
GetByteArrayElements() |
jbyteArray | jbyte |
GetCharArrayElements() |
jcharArray | jchar |
GetShortArrayElements() |
jshortArray | jshort |
GetIntArrayElements() |
jintArray | jint |
GetLongArrayElements() |
jlongArray | jlong |
GetFloatArrayElements() |
jfloatArray | jfloat |
GetDoubleArrayElements() |
jdoubleArray | jdouble |
Indices in the JNIEnv interface function table.
Table 4-9b Get<PrimitiveType>ArrayElements Family of Accessor RoutinesGet<PrimitiveType>ArrayElements Routines | Index |
---|---|
GetBooleanArrayElements() |
183 |
GetByteArrayElements() |
184 |
GetCharArrayElements() |
185 |
GetShortArrayElements() |
186 |
GetIntArrayElements() |
187 |
GetLongArrayElements() |
188 |
GetFloatArrayElements() |
189 |
GetDoubleArrayElements() |
190 |
env
: the JNI interface pointer.
array
: a Java string object.
isCopy
: a pointer to a boolean.
Returns a pointer to the array elements, or NULL
if
the operation fails.
void
Release<PrimitiveType>ArrayElements(JNIEnv
*env,
ArrayType
array,
NativeType *elems, jint mode);
A family of functions that informs the VM that the native code
no longer needs access to elems
. The
elems
argument is a pointer derived from
array
using the corresponding
Get<
PrimitiveType>
ArrayElements()
function. If necessary, this function copies back all changes made
to elems
to the original array.
The mode
argument provides information on how the
array buffer should be released. mode
has no effect if
elems
is not a copy of the elements in
array
. Otherwise, mode
has the following
impact, as shown in the following table:
mode | actions |
---|---|
0 |
copy back the content and free the
elems buffer |
JNI_COMMIT |
copy back the content but do not free
the elems buffer |
JNI_ABORT |
free the buffer without copying back the possible changes |
In most cases, programmers pass "0" to the mode
argument to ensure consistent behavior for both pinned and copied
arrays. The other options give the programmer more control over
memory management and should be used with extreme care.
The next table describes the specific routines that comprise the family of primitive array disposers. You should make the following substitutions:
Release<PrimitiveType>ArrayElements Routines | Array Type | Native Type |
---|---|---|
ReleaseBooleanArrayElements() |
jbooleanArray | jboolean |
ReleaseByteArrayElements() |
jbyteArray | jbyte |
ReleaseCharArrayElements() |
jcharArray | jchar |
ReleaseShortArrayElements() |
jshortArray | jshort |
ReleaseIntArrayElements() |
jintArray | jint |
ReleaseLongArrayElements() |
jlongArray | jlong |
ReleaseFloatArrayElements() |
jfloatArray | jfloat |
ReleaseDoubleArrayElements() |
jdoubleArray | jdouble |
Indices in the JNIEnv interface function table.
Table 4-11b Release<PrimitiveType>ArrayElements Family of Array RoutinesRelease<PrimitiveType>ArrayElements Routines | Index |
---|---|
ReleaseBooleanArrayElements() |
191 |
ReleaseByteArrayElements() |
192 |
ReleaseCharArrayElements() |
193 |
ReleaseShortArrayElements() |
194 |
ReleaseIntArrayElements() |
195 |
ReleaseLongArrayElements() |
196 |
ReleaseFloatArrayElements() |
197 |
ReleaseDoubleArrayElements() |
198 |
env
: the JNI interface pointer.
array
: a Java array object.
elems
: a pointer to array elements.
mode
: the release mode.
void
Get<PrimitiveType>ArrayRegion(JNIEnv
*env,
ArrayType array,
NativeType
jsize start, jsize len,*buf);
A family of functions that copies a region of a primitive array into a buffer.
The following table describes the specific primitive array element accessors. You should do the following substitutions:
Get<PrimitiveType>ArrayRegion Routine | Array Type | Native Type |
---|---|---|
GetBooleanArrayRegion() |
jbooleanArray | jboolean |
GetByteArrayRegion() |
jbyteArray | jbyte |
GetCharArrayRegion() |
jcharArray | jchar |
GetShortArrayRegion() |
jshortArray | jhort |
GetIntArrayRegion() |
jintArray | jint |
GetLongArrayRegion() |
jlongArray | jlong |
GetFloatArrayRegion() |
jfloatArray | jloat |
GetDoubleArrayRegion() |
jdoubleArray | jdouble |
Indices in the JNIEnv interface function table.
Table 4-12b Get<PrimitiveType>ArrayRegion Family of Array Accessor RoutinesGet<PrimitiveType>ArrayRegion Routine | Index |
---|---|
GetBooleanArrayRegion() |
199 |
GetByteArrayRegion() |
200 |
GetCharArrayRegion() |
201 |
GetShortArrayRegion() |
202 |
GetIntArrayRegion() |
203 |
GetLongArrayRegion() |
204 |
GetFloatArrayRegion() |
205 |
GetDoubleArrayRegion() |
206 |
env
: the JNI interface pointer.
array
: a Java array.
start
: the starting index.
len
: the number of elements to be copied.
buf
: the destination buffer.
ArrayIndexOutOfBoundsException
: if one of the
indexes in the region is not valid.
void
Set<PrimitiveType>ArrayRegion(JNIEnv
*env,
ArrayType array,
NativeType
jsize start, jsize len,*buf);
A family of functions that copies back a region of a primitive array from a buffer.
The following table describes the specific primitive array element accessors. You should make the following replacements:
Set<PrimitiveType>ArrayRegion Routine | Array Type | Native Type |
---|---|---|
SetBooleanArrayRegion() |
jbooleanArray | jboolean |
SetByteArrayRegion() |
jbyteArray | jbyte |
SetCharArrayRegion() |
jcharArray | jchar |
SetShortArrayRegion() |
jshortArray | jshort |
SetIntArrayRegion() |
jintArray | jint |
SetLongArrayRegion() |
jlongArray | jlong |
SetFloatArrayRegion() |
jfloatArray | jfloat |
SetDoubleArrayRegion() |
jdoubleArray | jdouble |
Indices in the JNIEnv interface function table.
Table 4-13b Set<PrimitiveType>ArrayRegion Family of Array Accessor RoutinesSet<PrimitiveType>ArrayRegion Routine | Index |
---|---|
SetBooleanArrayRegion() |
207 |
SetByteArrayRegion() |
208 |
SetCharArrayRegion() |
209 |
SetShortArrayRegion() |
210 |
SetIntArrayRegion() |
211 |
SetLongArrayRegion() |
212 |
SetFloatArrayRegion() |
213 |
SetDoubleArrayRegion() |
214 |
PARAMETERS:
env
: the JNI interface pointer.
array
: a Java array.
start
: the starting index.
len
: the number of elements to be copied.
buf
: the source buffer.
ArrayIndexOutOfBoundsException
: if one of the
indexes in the region is not valid.
Note: In SDK/JRE 1.1, programmers can use
New functions introduced in SDK/JRE 1.3 allow native code to obtain a direct pointer to array elements even if the VM does not support pinning. |
void * GetPrimitiveArrayCritical(JNIEnv *env, jarray
array, jboolean *isCopy);
void ReleasePrimitiveArrayCritical(JNIEnv *env, jarray array, void
*carray, jint mode);
The semantics of these two functions are very similar to the
existing Get/Release<PrimitiveType>ArrayElements
functions. If possible, the VM returns a pointer to the primitive
array; otherwise, a copy is made. However, there are
significant restrictions on how these functions can be
used.
After calling GetPrimitiveArrayCritical
, the native
code should not run for an extended period of time before it calls
ReleasePrimitiveArrayCritical
. We must treat the code
inside this pair of functions as running in a "critical region."
Inside a critical region, native code must not call other JNI
functions, or any system call that may cause the current thread to
block and wait for another Java thread. (For example, the current
thread must not call read
on a stream being written by
another Java thread.)
These restrictions make it more likely that the native
code will obtain an uncopied version of the array, even if the VM
does not support pinning. For example, a VM may
temporarily disable garbage collection when the native code is
holding a pointer to an array obtained via
GetPrimitiveArrayCritical
.
Multiple pairs of GetPrimtiveArrayCritical
and
ReleasePrimitiveArrayCritical
may be nested. For
example:
jint len = (*env)->GetArrayLength(env, arr1); jbyte *a1 = (*env)->GetPrimitiveArrayCritical(env, arr1, 0); jbyte *a2 = (*env)->GetPrimitiveArrayCritical(env, arr2, 0); /* We need to check in case the VM tried to make a copy. */ if (a1 == NULL || a2 == NULL) { ... /* out of memory exception thrown */ } memcpy(a1, a2, len); (*env)->ReleasePrimitiveArrayCritical(env, arr2, a2, 0); (*env)->ReleasePrimitiveArrayCritical(env, arr1, a1, 0);
Note that GetPrimitiveArrayCritical
might still
make a copy of the array if the VM internally represents arrays in
a different format. Therefore we need to check its return value
against NULL
for possible out of memory situations.
Linkage Index 222 in the JNIEnv interface function table.
Linkage Index 223 in the JNIEnv interface function table.
SDK/JRE 1.2
jint RegisterNatives(JNIEnv *env, jclass clazz,
const JNINativeMethod *methods, jint nMethods);
Registers native methods with the class specified by the
clazz
argument. The methods
parameter
specifies an array of JNINativeMethod
structures that
contain the names, signatures, and function pointers of the native
methods. The nMethods
parameter specifies the number
of native methods in the array. The JNINativeMethod
structure is defined as follows:
typedef struct { char *name; char *signature; void *fnPtr; } JNINativeMethod;
The function pointers nominally must have the following signature:
ReturnType (*fnPtr)(JNIEnv *env, jobject objectOrClass, ...);
Index 215 in the JNIEnv interface function table.
env
: the JNI interface pointer.
clazz
: a Java class object.
methods
: the native methods in the class.
nMethods
: the number of native methods in the
class.
Returns "0" on success; returns a negative value on failure.
NoSuchMethodError
: if a specified method cannot be
found or if the method is not native.
jint UnregisterNatives(JNIEnv *env, jclass
clazz);
Unregisters native methods of a class. The class goes back to the state before it was linked or registered with its native method functions.
This function should not be used in normal native code. Instead, it provides special programs a way to reload and relink native libraries.
env
: the JNI interface pointer.
clazz
: a Java class object.
Returns "0" on success; returns a negative value on failure.
jint MonitorEnter(JNIEnv *env, jobject obj);
Enters the monitor associated with the underlying Java object
referred to by obj
.
Each Java object has a monitor associated with it. If the
current thread already owns the monitor associated with
obj
, it increments a counter in the monitor indicating
the number of times this thread has entered the monitor. If the
monitor associated with obj
is not owned by any
thread, the current thread becomes the owner of the monitor,
setting the entry count of this monitor to 1. If another thread
already owns the monitor associated with obj
, the
current thread waits until the monitor is released, then tries
again to gain ownership.
env
: the JNI interface pointer.
obj
: a normal Java object or class object.
Returns "0" on success; returns a negative value on failure.
jint MonitorExit(JNIEnv *env, jobject obj);
The current thread must be the owner of the monitor associated
with the underlying Java object referred to by obj
.
The thread decrements the counter indicating the number of times it
has entered this monitor. If the value of the counter becomes zero,
the current thread releases the monitor.
env
: the JNI interface pointer.
obj
: a normal Java object or class object.
Returns "0" on success; returns a negative value on failure.
The NIO-related entry points allow native code to access
java.nio
direct buffers. The contents of a
direct buffer can, potentially, reside in native memory outside of
the ordinary garbage-collected heap. For information about direct
buffers, please see New I/O APIs
and the specification of the java.nio.ByteBuffer
class.
Every implementation of the Java virtual machine must support these functions, but not every implementation is required to support JNI access to direct buffers. If a JVM does not support such access then the NewDirectByteBuffer and GetDirectBufferAddress functions must always return NULL, and the GetDirectBufferCapacity function must always return -1. If a JVM does support such access then these three functions must be implemented to return the appropriate values.
jobject NewDirectByteBuffer(JNIEnv* env, void* address, jlong capacity);
Allocates and returns a direct java.nio.ByteBuffer referring to the block of memory starting at the memory address address and extending capacity bytes.
Native code that calls this function and returns the resulting byte-buffer object to Java-level code should ensure that the buffer refers to a valid region of memory that is accessible for reading and, if appropriate, writing. An attempt to access an invalid memory location from Java code will either return an arbitrary value, have no visible effect, or cause an unspecified exception to be thrown.
Index 229 in the JNIEnv interface function table.
env: the JNIEnv interface pointer
address: the starting address of the memory region (must not be NULL)
capacity: the size in bytes of the memory region (must be positive)
Returns a local reference to the newly-instantiated java.nio.ByteBuffer object. Returns NULL if an exception occurs, or if JNI access to direct buffers is not supported by this virtual machine.
OutOfMemoryError: if allocation of the ByteBuffer object fails
SDK/JRE 1.4
void* GetDirectBufferAddress(JNIEnv* env, jobject buf);
Fetches and returns the starting address of the memory region referenced by the given direct java.nio.Buffer.
This function allows native code to access the same memory region that is accessible to Java code via the buffer object.
Index 230 in the JNIEnv interface function table.
env: the JNIEnv interface pointer
buf: a direct java.nio.Buffer object (must not be NULL)
Returns the starting address of the memory region referenced by the buffer. Returns NULL if the memory region is undefined, if the given object is not a direct java.nio.Buffer, or if JNI access to direct buffers is not supported by this virtual machine.
SDK/JRE 1.4
jlong GetDirectBufferCapacity(JNIEnv* env, jobject buf);
Fetches and returns the capacity in bytes of the memory region referenced by the given direct java.nio.Buffer.
Index 231 in the JNIEnv interface function table.
env: the JNIEnv interface pointer
buf: a direct java.nio.Buffer object (must not be NULL)
Returns the capacity in bytes of the memory region associated with the buffer. Returns -1 if the given object is not a direct java.nio.Buffer, or if JNI access to direct buffers is not supported by this virtual machine.
SDK/JRE 1.4
Programmers can use the JNI to call Java methods or access Java fields if they know the name and type of the methods or fields. The Java Core Reflection API allows programmers to introspect Java classes at runtime. JNI provides a set of conversion functions between field and method IDs used in the JNI to field and method objects used in the Java Core Reflection API.
jmethodID FromReflectedMethod(JNIEnv *env, jobject
method);
Converts a java.lang.reflect.Method
or
java.lang.reflect.Constructor
object to a method
ID.
Index 7 in the JNIEnv interface function table.
SDK/JRE 1.2
jfieldID FromReflectedField(JNIEnv *env, jobject
field);
Converts a java.lang.reflect.Field
to a field
ID.
SDK/JRE 1.2
jobject ToReflectedMethod(JNIEnv *env, jclass cls,
jmethodID methodID);
Converts a method ID derived from cls
to a
java.lang.reflect.Method
or
java.lang.reflect.Constructor
object.
Throws OutOfMemoryError
and returns 0 if fails.
Index 9 in the JNIEnv interface function table.
SDK/JRE 1.2
jobject ToReflectedField(JNIEnv *env, jclass cls,
jfieldID fieldID);
Converts a field ID derived from cls
to a
java.lang.reflect.Field
object.
Throws OutOfMemoryError
and returns 0 if fails.
Index 12 in the JNIEnv interface function table.
SDK/JRE 1.2
jint GetJavaVM(JNIEnv *env, JavaVM **vm);
Returns the Java VM interface (used in the Invocation API)
associated with the current thread. The result is placed at the
location pointed to by the second argument, vm
.
Index 219 in the JNIEnv interface function table.
env
: the JNI interface pointer.
vm
: a pointer to where the result should be
placed.
Returns "0" on success; returns a negative value on failure.
Contents | Previous | Next |